Open topic with navigation

IDLnetOGCWMS

Superclasses | Creation | Properties | Methods | Examples | Version History

An IDLnetOGCWMS object lets you access a Web Map Service (WMS) server that supports the Open Geospatial Consortium (OGC) standards. The OGC is an international group working to develop standards for the exchange of geospatial content and services including specifications for web delivery of data that combines location and geospatial information.

For additional information on IDL’s WMS features, see the following sections:

• Web Map Service (WMS) Overview
• Supported OGC WMS Version
• Making OGC WMS Server Requests
• Translating a URL into Property Values
• Using Callbacks with the IDLnetOGCWMS Object
• HTTP Authentication, Security and Encoding

Note: A sample IDL program included in the IDL distribution provides a generic WMS browser that lets you peruse and request coverages from a remote OGC server. See Sample WMS Browser for details.

Superclasses

None

Creation

See IDLnetOGCWMS::Init.

Properties

Objects of this class have the following properties. See IDLnetOGCWMS Properties for details on individual properties.

Methods

This class has the following methods:

• IDLnetOGCWMS::Cleanup
• IDLnetOGCWMS::GetCapabilities
• IDLnetOGCWMS::GetFeatureInfo
• IDLnetOGCWMS::GetLayers
• IDLnetOGCWMS::GetMap
• IDLnetOGCWMS::GetProperty
• IDLnetOGCWMS::GetServiceSection
• IDLnetOGCWMS::Init
• IDLnetOGCWMS::ParseUrl
• IDLnetOGCWMS::SetProperty

Examples

See the following methods for examples:

• IDLnetOGCWMS::GetLayers
• IDLnetOGCWMS::GetMap

Sample WMS Browser

The IDL distribution includes a sample program that allows you to enter a working URL to an OGC server and then call GetCapabilities, GetMap and GetFeatureInfo from within the user interface. You can modify property values and query characteristics to return the desired data. To run the browser program, enter OGC_WMS at the command line. See the browser help for more information.

Tip: You can use the example IDL OGC WMS Browser as a template for creating an application that queries a remote WMS server. This example is located in the IDL_DIR\examples\ogc\wms directory where IDL_DIR is the directory where you have installed IDL. Running the example lets you parse a known, working URL to an OGC WMS server, and then make GetCapabilities, GetMap and GetFeatureInfo requests. By default, returned files are written to your application user directory, a subdirectory of your home directory.

Version History

Web Map Service (WMS) Overview

A request for map data from an OGC WMS server involves three main requests: GetCapabilities, GetMap, and GetFeatureInfo. The following describes these operations in terms of the IDLnetOGCWMS object:

• GetCapabilities — a general query that returns information about what types of requests are allowed and available. This includes service and summary information about data collections that are contained in “layers,” which is transmitted in an XML file that is written to disk.
• GetMap — a request that asks for one or more specific layers containing geographic information where each layer can be individually rendered. The server returns requested layers in an image file that is written to disk.
• GetFeatureInfo — a request for data relating to a feature on a map identified by map coordinates. If supported by the server, the server transmits information about the feature to a file that is written to disk. There are no standards dictating the availability or content of such information.

For details on how to use the IDLnetOGCWMS object properties and methods to request and receive information from an OGC server, see Making OGC WMS Server Requests. Also see Sample WMS Browser for information about the IDL OGC WMS Browser, a sample program included in the IDL distribution.

Additional OGC Web Map Service Resources

The Open Geospatial Consortium web site provides complete details on the Web Map Service protocol including the WMS specification and schema documents. You may find the following documents helpful if you need additional WMS resources. See OGC web site (www.opengeospatial.org) to search for these and other resource files.

Supported OGC WMS Version

This object supports version 1.1.1 and 1.3.0 of the OGC WMS standard. The IDLnetOGCWMS object conforms to the OGC WMS standard and is designed to communicate with OGC WMS compliant servers.

Note: Since this object is designed as an OGC WMS client, OGC WMS certification is not applicable. Compliance testing and certification is valid only for WMS servers.

Making OGC WMS Server Requests

This section outlines the steps required to query and return information from an OGC server. The goal is to return one or more layers as a rendered image map file. Broadly, an information request from a WMS sever requires determining what data is available from a server (layers), determining what data you want to request (the layer definition), making the request, and returning rendered map data. You then have the option to request specific information about a map feature if desired and if supported by the server.

Note: You can implement a callback to return information about the status of requests. See Using Callbacks with the IDLnetOGCWMS Object for details.

After you create an IDLnetOGCWMS object, you will need to complete the following steps:

1. Identify the WMS server. The easiest way to do this is to pass a working URL to the IDLnetOGCWMS::ParseUrl method, which sets the required URL_HOSTNAME and URL_PATH properties. Alternately, manually set properties related to the URL. See Translating a URL into Property Values for information on which URL components belong to which IDLnetOGCWMS properties.

   If dealing with secure WMS servers, see HTTP Authentication, Security and Encoding for additional information.

2. Determine what information is available on the WMS server by making a GetCapabilities request. This typically returns and parses an XML file that contains information about the available layers. See IDLnetOGCWMS::GetCapabilities for details. You can modify the CAPABILITIES_FILENAME property to specify where the resulting file is stored.
3. Return the information contained in the layers by calling IDLnetOGCWMS::GetLayers. You must call this method to return information for the specified layer(s) in an IDL structure. The NAME field value of this structure is required to request additional information from an OGC server using the GetMap method, described next. If you wish, you can also call IDLnetOGCWMS::GetServiceSection to return service information from the XML file, but this is not necessary.
4. Use IDLnetOGCWMS::GetMap to request the combination of one or more layers into a map, specifying the desired layers via the Map_Request argument. You can modify the MAP_FILENAME property to specify where the resulting file is stored.
5. Access the information about features in the map by calling IDLnetOGCWMS::GetFeatureInfo. (The OGC WMS server may not offer this support for every layer, and there may not be information available for every feature). You can modify the FEATURE_INFO_FILENAME property to specify where the resulting file is stored.

Translating a URL into Property Values

A valid WMS server URL is required to establish communication with an OGC WMS server. Additionally, IDLnetOGCWMS URL-related property values must be set before data can be successfully requested from a OGC WMS server. Either set the required properties manually (using SetProperty) or pass a URL to ParseURL. The IDLnetOGCWMS::ParseUrl method automatically parses a given URL and sets related property values.

Note: Regardless of how properties are set, the URL_HOSTNAME and URL_PATH properties must be set before calling the GetCapabilities, GetMap or GetFeatureInfo methods.

The following table describes how the components of a given URL should be assigned to property values. Consider the following URL (which would typically exist on a single line):

http://my.hostname.com:8080/demo/cgi_path?CustomPrefix&

Version=1.1.1&SERVICE=WMS&CustomMiddle&Request=GetCapabilities&

CustomSuffix

Components of this URL map to properties as follows.

The query portion of the URL passed to a WMS server (the parameter=value pairs following the ? character) always includes the following three parameters:

• Version takes its value from the WMS_VERSION property
• Service is set equal to “WMS” for the IDLnetOGCWMS object
• Request is one of “GetCapabilities” “GetMap”, or “GetFeatureInfo” depending on the method in use

These three parameters are inserted into the URL automatically by IDL; any values specified for these parameters in the URL are ignored. They are not included when the URL_QUERY_PREFIX or URL_QUERY_SUFFIX properties are returned by the GetProperty method. Any query parameters that precede any of the three required parameters will be included in the URL_QUERY_PREFIX property by the ParseURL method; other nonrequired parameters will be included in the URL_QUERY_SUFFIX property.

Note: If not specified in the URL, property values besides URL_HOSTNAME and URL_PATH are set to default values. For example, the URL_PORT property defaults to 80 and the WMS_VERSION defaults to 1.1.1.

Using Callbacks with the IDLnetOGCWMS Object

Callbacks from the IDLnetOGCWMS object provide a way to transmit information back to the caller based on the status of a request made to a remote OGC WMS server. The value returned by the callback function is then used by the IDLnetOGCWMS object to determine whether to continue or abort the request.

The IDLnetOGCWMS object lets you define functions (written in IDL) that will be called during a GetCapabilities, GetMap, or GetFeatureInfo method call. If a callback function is specified via the CALLBACK_FUNCTION property, it is called in the following circumstances:

• For the IDLnetOGCWMS::GetCapabilities method, the callback function is called each time a packet is received from the OGC WMS server. If the FROM_FILE keyword is set, the callback function is called before and after the XML file is parsed.
• For the IDLnetOGCWMS::GetMap method, the callback function is called each time a packet is received from the OGC WMS server.
• For the IDLnetOGCWMS::GetFeatureInfo method, the callback function is called each time a packet of data is received from the OGC WMS server.

All methods invoke the callback function with an array of strings indicating status as the first parameter, an array of integers containing progress information as the second parameter, and with the value (if any) specified by the CALLBACK_DATA property as the third parameter. A callback function returns a value of type Int.

Cancelling a Request

The return value of the callback function should be an integer zero or one. If the return value is zero, a cancel message will be sent to the remote node. If the return value is one, the operation will continue.

Callback Routine Signature

A callback function is written in IDL and has the following signature:

Function Callback_Function_Name, StatusInfo, ProgressInfo,    CallbackData

where

• Callback_Function_Name is the name of the callback function. This value is specified as the value of the CALLBACK_FUNCTION property.
• StatusInfo is an array of strings that contain status information about the operation. The status strings are provided for information and human inspection rather than for programmatic processing; the exact strings included in the array will depend on numerous factors including the status of the operation and the type of OGC WMS server.
• ProgressInfo is an array of five 64-bit long integers that contain progress information for the transfer:
• ProgressInfo[0] – Contains 1 (one) when the ProgressInfo array contains valid data, or 0 (zero) when the array does not contain valid data.
• ProgressInfo[1] – Contains the total number of bytes to be downloaded. This array element will contain 0 (zero) when the transfer encoding is “chunked.”
• ProgressInfo[2] – Contains the number of bytes that have been downloaded during the current transfer.
• ProgressInfo[3] – Contains the total number of bytes to be uploaded.
• ProgressInfo[4] – Contains the number of bytes that have been uploaded during the current transfer.
• CallbackData is the data specified via the CALLBACK_DATA property. The value of this property is passed to the callback function unmodified. If the CALLBACK_DATA property is unspecified, an integer zero is passed to the callback function as the value of this parameter.

The CallbackData parameter is useful for passing static information, such as the widget ID of a widget where the status information is displayed or a pointer to a complex data structure, from the IDLnetOGCWMS object to the callback routine.

For a simple example of using a callback to return additional status information, see IDLnetOGCWMS::GetCapabilities. The StatusInfo details are printed to the Output window.

HTTP Authentication, Security and Encoding

The following sections describe the IDLnetOGCWMS object’s support of HTTP protocols including:

• HTTP Authentication
• HTTP Security
• HTTP Encoding

HTTP Authentication

The IDLnetOGCWMS object supports the following HTTP authentication modes for WMS and proxy servers:

• Disabled—no authentication
• Basic—plain text transmission of username and password
• Digest—encrypted transmission of username and password

By default, AUTHENTICATION and PROXY_AUTHENTICATION properties are set to “Basic and Digest” option, meaning that either basic or digest authentication are supported. However, for this setting to be honored, the corresponding username and password properties must also be set:

• For authentication on an OGC server, set USERNAME and PASSWORD properties
• For authentication on a proxy server, set PROXY_USERNAME and PROXY_PASSWORD properties

HTTP Security

The IDLnetOGCWMS object also supports HTTPS through the implementation of Secure Socket Layer (SSL). With SSL encryption, all requests and responses are encrypted. When the URL_SCHEME property is set to “https”, use the SSL_CERTIFICATE_FILE, SSL_VERIFY_HOST, and SSL_VERIFY_PEER properties to define security-related parameters.

Note: If you receive a PRNG (Pseudo Random Number Generator) error when attempting to use HTTPS on UNIX, you need to install either dev/random or dev/urandom in order to generate secure keys.

HTTP Encoding

The IDLnetOGCWMS object supports compressed and encoded responses from a remote OGC WMS server. Supported encoding formats are:

• DEFLATE
• GZIP

See the ENCODE property for details.